Associating Styles With Shapes (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Associating Styles With Shapes
QuickDraw GX provides two basic methods of altering stylistic information for shapes:

using functions that operate on style objects directly
using functions that operate on style objects indirectly through shape objects

The first category of functions require you to provide a reference to a style object, which you can obtain by using the GXNewStyle function to create a new style object, or by using the GXGetShapeStyle function to obtain a reference to an existing style object. (The GXNewStyle and GXGetShapeStyle functions are described in Inside Macintosh: QuickDraw GX Objects.)
Once you have a reference to a style object, you can use this category of functions to manipulate the style's properties; for example, you can use the GXSetStylePen function to change the pen width of the style.
If you obtained the reference to the style object using the GXGetShapeStyle function, then the style is already associated with a shape--in fact, it may be shared amongst many shapes. Modifications you make to the style's properties will apply to all shapes that share the style.
However, if you created the style object using the GXNewStyle function, you must then associate the style with a shape for the style modifications to have any effect. You can associate a style with a shape using the GXSetShapeStyle function, as shown in Listing 3-1. The GXSetShapeStyle function is described in Inside Macintosh: QuickDraw GX Objects.
Listing 3-1 Adding style information by directly manipulating a style object
void MakeThickPenStyle(void)
{
   gxShape aRectangleShape;
   gxStyle aThickPenStyle;

   static gxRectangle rectangleGeometry = {ff(50), ff(50), 
                                           ff(200), ff(200)};
                           

   aRectangleShape = GXNewRectangle(&rectangleGeometry);
   GXSetShapeFill(aRectangleShape, gxClosedFrameFill);
   
   aThickPenStyle = GXNewStyle();
   GXSetStylePen(aThickPenStyle, ff(30));
   
   GXSetShapeStyle(aRectangleShape, aThickPenStyle);
   GXDisposeStyle(aThickPenStyle);
   
   GXDrawShape(aRectangleShape);
   
   GXDisposeShape(aRectangleShape);
}
The MakeThickPenStyle sample function creates a rectangle shape and sets its shape fill to the closed-frame shape fill, making it a framed rectangle. The sample function then creates a new style object using the GXNewStyle function, which creates a style object with properties set to the standard initialized values. The owner count of this style object is 1, corresponding to the reference contained in the aThickPenStyle variable. The sample function then alters the pen width of the new style using the GXSetStylePen function.
To associate the style with the rectangle shape, the sample function calls the GXSetShapeStyle function. This function disposes of the style previously referenced by the rectangle shape, stores a reference to the new style in the rectangle shape object, and increments the style's owner count--there are now two references to the style: one in the sample function's local variable, and one in the rectangle shape.
Finally, the sample function disposes of the style, which indicates that the reference to the style stored in the local variable aThickPenStyle is no longer needed. QuickDraw GX decrements the owner count of the style, which becomes 1, corresponding to the reference contained in the rectangle shape.
Finally, the sample function draws the rectangle, which appears as in Figure 3-34.
Figure 3-34 Rectangle with thick pen

The second method of altering styles involves functions that operate on style objects indirectly through the shape objects that reference them.
When using this category of function, you need only provide a reference to the shape whose style information you want to change. QuickDraw GX finds the associated style object and alters the appropriate style property for you.
In fact, QuickDraw GX provides one further level of service with this category of functions. If the shape that you specify is sharing its style with other shapes, QuickDraw GX first makes a copy of the style object, associates the copy with the shape you specified, and then alters the appropriate property of the copy.
Listing 3-2 shows an alternate approach to creating the thick-framed rectangle from Listing 3-1.
Listing 3-2 Manipulating style information indirectly
void MakeThickRectangle(void)
{
   gxShape aRectangleShape;

   gxRectangle rectangleGeometry = {ff(50), ff(50), 
                                    ff(200), ff(200)};
                           

   aRectangleShape = GXNewRectangle(&rectangleGeometry);
   GXSetShapeFill(aRectangleShape, gxHollowFill);
   
   GXSetShapePen(aRectangleShape, ff(30));
   
   GXDrawShape(aRectangleShape);
   
   GXDisposeShape(aRectangleShape);
}
As in Listing 3-1, this sample function creates a new framed rectangle shape. However, instead of creating a style object, altering the pen width property of the style object with the GXSetStylePen function, and associating the style with the rectangle shape, this sample function uses the GXSetShapePen function to accomplish those tasks in one step.
Since the rectangle shape is a new shape, it shares its style object with other shapes--the default rectangle shape at the very least. The GXSetShapePen function notices that the rectangle shape's style is shared, so it makes a copy of this style, associates the copy with the rectangle shape, and alters the pen width property of this copy.
The result of this sample function looks exactly the same as the result of the previous sample function, shown in Figure 3-34.
For simplicity, the rest of the sample functions in this chapter use the second method for altering style properties.